SoftQuad HoTMetaL for Microsoft Windows Standard identification SoftQuad HoTMetaL is an SGML Application Conforming to International Standard ISO 8879 - Standard Generalized Markup Language. Published by SoftQuad Inc. 56 Aberfoyle Crescent Suite 810 Toronto, Canada M8X 2W4 Telephone: (416) 239-4801 Fax: (416) 239-7105 Internet: hotmetal@sq.com WWW: http://www.sq.com Document version SoftQuad HoTMetaL for Microsoft Windows Second Edition (February 1995) SoftQuad Inc. makes no warranty of any kind with respect to the completeness or accuracy of this book. SoftQuad may make improvements and/or changes to the product(s) and/or programs described in this book at any time and without notice. Copyrights and trademarks (c) 1995 SoftQuad Inc. All rights reserved. No part of this book may be reproduced, stored in a retrieval system, or transmitted in any form or by any means--electronic, mechanical, recording, or otherwise--without the prior written consent of the publisher, excepting brief quotes used in connection with reviews written specifically for inclusion in a magazine or newspaper. SoftQuad HoTMetaL and SoftQuad HoTMetaL PRO are trademarks of SoftQuad Inc. NCSA Mosaic is a trademark of the University of Illinois. Enhanced NCSA Mosaic is a trademark of Spyglass, Inc. Netscape is a trademark of Netscape Communications Corp. Microsoft Windows is a trademark of Microsoft Corporation. Notice Agencies of the United States Government please note: RESTRICTED RIGHTS LEGEND: Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 52.227-7013 and in similar clauses in the FAR and NASA FAR Supplement. 1. About this manual 1.1. Your suggestions 2. A guide for the perplexed 2.1. Purpose: editors and browsers 2.2. An overview of the menus 2.3. How to run HoTMetaL 2.4. Associating HoTMetaL with HTML files 2.5. Setting the HoTMetaL directory 2.6. Creating and editing files 2.6.1. Creating a new file 2.6.2. Editing an existing HTML file 2.7. Configuring HoTMetaL 2.7.1. Configuration files 2.7.2. Configuration variables read on start-up! 2.7.3. Setting parameters in the configuration files 2.7.3.1. Basic format for setting variables 2.8. Launching browsers and viewers 2.9. Text and markup 2.10. Templates 2.11. A tutorial on creating documents with HoTMetaL 2.11.1. Getting started: a basic document 2.11.2. Character formatting: Adding emphasis to inline text 2.11.3. Formatting blocks of text 2.11.4. Lists 2.11.4.1. Ordered (numbered) lists 2.11.4.2. Unordered lists 2.11.5. Links and URLs 2.11.5.1. Anchors 2.11.5.2. Links within the same document 2.11.5.3. Images 2.11.6. Forms 2.11.6.1. Actions 2.11.6.2. Creating a text box 2.11.6.3. Entering several lines of text 2.11.6.4. Presenting a list of choices 2.11.6.5. Check boxes 2.11.6.6. Radio buttons 2.11.6.7. Reset 2.11.6.8. Submitting the form 2.12. HTML quick reference 2.12.1. Overview 2.12.2. Block formatting 2.12.3. Character formatting 2.12.3.1. Line breaks 2.12.3.2. Horizontal lines 2.12.4. List elements 2.12.5. Link elements 2.12.5.1. Links within the same document 2.12.5.2. `Hot images' 2.12.5.3. Images with hot spots 2.12.6. Forms 2.12.7. Other elements 2.12.8. Obsolete elements 2.12.9. Proposed elements 2.13. If you see something you like... 2.14. For further information... 2.15. The structure of HTML documents 2.15.1. Rules files 2.16. Commands for inserting markup 2.17. Screen formatting 2.17.1. Styles 2.17.2. Displaying images 2.17.3. Previewing the document 2.17.4. Displaying icons 2.17.5. Displaying a document outline 2.17.6. Newlines 2.18. Attributes 2.18.1. Viewing attribute values 2.18.2. Editing attributes 2.19. Netscape support 3. The File menu 3.1. New 3.2. Open... 3.2.1. Error checking 3.3. Open Template... 3.3.1. Opening a template 3.3.2. Creating your own templates 3.3.2.1. Templates directory 3.3.2.2. Creating templates 3.3.2.3. Installing a template 3.4. Save 3.4.1. Save options 3.5. Save As... 3.6. Close File 3.7. Preview 3.8. Publish... 3.8.1. Finding and Replacing URLs 3.9. Exit 4. The Edit menu 4.1. Undo 4.1.1. Undo limit 4.2. Redo 4.3. Cut 4.4. Copy 4.5. Paste 4.6. Find and Replace... 4.6.1. Specifying the search and replace strings 4.6.2. Command buttons 4.6.2.1. Find 4.6.2.2. Replace 4.6.2.3. Replace then Find 4.6.2.4. Replace All 4.6.3. Specifying search patterns 4.6.4. Elements and character entities as search patterns 4.6.4.1. Searching for text within an element 4.6.5. Error messages 4.6.6. Other search options 4.6.6.1. Whole Words 4.6.6.2. Case Sensitive 4.6.6.3. Backwards Search 4.6.6.4. Wrap 4.6.6.5. Find Patterns 4.6.7. Find In 4.7. Find Next 5. The View menu 5.1. Numerical values 5.1.1. Examples 5.1.2. Relative and percentage settings 5.2. Show/Hide Tags 5.3. Show/Hide Link and Context View 5.4. Show/Hide Structure View 5.4.1. Editing in the structure view 5.4.2. Expanding the view of elements 5.5. Show Image 5.6. Show/Hide Inline Images 5.7. Show/Hide URLs 5.8. Character... 5.8.1. Setting an element's formatting 5.8.2. Setting the default formatting 5.8.3. Font Family 5.8.3.1. Adopt Current 5.8.4. Font Size 5.8.5. Font Style 5.8.5.1. Bold, Italic 5.8.5.2. Superscript, Subscript 5.8.5.3. Toggle 5.8.5.4. Adopt Current 5.8.5.5. Underline 5.8.6. Line Height 5.8.7. Justification 5.8.8. Fill 5.8.8.1. Saving filled elements 5.8.9. Format Types 5.8.9.1. Block 5.8.9.2. Inline 5.9. Separation... 5.9.1. Top and bottom space 5.9.2. Tabbed elements 6. The Markup menu 6.1. Interpret Document 6.2. Insert Element... 6.2.1. The list of elements 6.2.2. Inserting an element 6.2.3. Restrictions 6.2.4. Required elements 6.3. Surround... 6.4. Change... 6.5. Edit SGML Attributes... 6.6. Insert Character Entity... 6.6.1. Inserting a character entity 6.6.2. Displaying character entities 6.7. Turn Rules Checking On/Off 7. The Help menu 7.1. About HoTMetaL... 7.2. SoftQuad Home Page 8. The Window menu 8.1. Next 8.2. Previous 8.3. Cascade 8.4. Tile 8.5. Tile Vertically 8.6. Arrange Icons 8.7. Filenames in the Windows menu 9. The configuration mechanism 9.1. Configuring HoTMetaL 9.1.1. Configuration files 9.1.2. Configuration variables read on start-up! 9.1.3. A suggestion: base and personal configuration files 9.1.3.1. Base file 9.1.3.2. Personal file 9.1.4. Setting parameters in the configuration files 9.1.4.1. Basic format for setting variables 9.1.4.2. Referencing one variable from another 9.1.4.3. Appending and prepending to a variable 9.2. Control variables 9.2.1. Save options 9.2.1.1. export_doc_type_dec 9.2.1.2. export_sgml_dec 9.2.1.3. export_add_line_breaks 9.2.1.4. export_max_line_len 9.2.1.5. export_convert_special_chars 9.2.1.6. export_eol 9.2.2. Find options 9.2.2.1. find_whole_words 9.2.2.2. find_case_sensitive 9.2.2.3. find_backward 9.2.2.4. find_wrap 9.2.2.5. find_patterns 9.2.3. Markup options 9.2.3.1. include_required_elements 9.2.3.2. prompt_for_attrs 9.2.4. Display variables 9.2.4.1. default_font_name 9.2.4.2. default_font_size 9.2.4.3. tag_font_name 9.2.4.4. tag_font_size 9.2.5. Other options 9.2.5.1. html_browser 9.2.5.2. publish_change_from 9.2.5.3. publish_change_to 9.2.5.4. show_inline_images 9.2.5.5. undo_limit 9.2.5.6. view_gif 9.3. Location variables 9.3.1. Paths and directories 9.3.1.1. import_path 9.3.1.2. export_path 9.3.1.3. import_path 9.3.1.4. save_path 9.3.1.5. styles_path 9.3.1.6. templates_path 9.3.2. Files 9.3.2.1. rgb_txt 9.3.3. File extensions 9.3.3.1. styles_ext 9.4. Tracing configuration variables 10. Appendix 1: Keyboard shortcuts 10.1. Shortcuts 10.2. Mnemonics 1. About this manual This manual consists of: 1. A guide for the perplexed, an introduction and tutorial for HoTMetaL and HTML. 2. A chapter on each of the menus. 3. A chapter on the configuration mechanism. 4. An appendix on keyboard shortcuts. 1.1. Your suggestions SoftQuad welcomes your comments and suggestions on this documentation. These will be carefully considered for future versions of the HoTMetaL manual. You may contact us at the following address: hotmetal-doc@sq.com 2. A guide for the perplexed This chapter tells you how to start up HoTMetaL and gives the basic information you need to get going with creating and editing files. It contains the sections on the following topics: - Purpose of HoTMetaL - How to run HoTMetaL - Creating and editing files - Configuring HoTMetaL - Text and markup - Tutorial on HoTMetaL and creating web documents - HTML quick reference - Screen formatting in HoTMetaL - Attributes If you are new to HoTMetaL or HTML, you should certainly read this chapter, as it will help you get acquainted with the product and learn about the components and procedures you'll need to get your work done. 2.1. Purpose: editors and browsers HoTMetaL is an editor for creating files that can be read by graphical browsers (such as Mosaic) that are connected to the World Wide Web (WWW). The file format for such files is called Hypertext Markup Language (HTML). The main difference between an editor like HoTMetaL and browsers is that HoTMetaL is for editing files and browsers are for retrieving, displaying, and reading files. Any text editor can create an HTML file (but we believe that HoTMetaL is a more convenient and pleasant way of doing it!) Browsers take a file saved by HoTMetaL, consisting of text and markup, and do things like screen formatting, generating graphical forms, issuing mail messages, and so forth. It's important to understand that the different kinds of programs do different things. There are many browsers available, and they can process the same HTML file in different ways--and these are outside the control of HoTMetaL! What is in HoTMetaL's control is creating correctly marked-up documents. Note: The HTML format is actually a type of file format based on the Standard Generalized Markup Language (SGML). All HTML files are SGML files (the converse is not true, however--there are many other file formats described by SGML, so most SGML files are not in HTML format.) Some browsers have a command that lets you see what the HTML form of the current document looks like; you can also save the file in HTML format and view it with a text editor. HoTMetaL provides an easy-to-use, graphical, structured editor for creating files in this format. 2.2. An overview of the menus This section provides a summary of the main features. + File menu: file manipulation, e.g., opening and closing files; filtering input files. + Edit menu: cutting and pasting; finding and replacing strings and patterns; spell checking. + View menu: screen formatting; displaying different views of the document. + Markup menu: inserting and changing markup; editing URLs; checking document conformance. + Help menu. 2.3. How to run HoTMetaL The usual way to run HoTMetaL is by double-clicking on the icon labeled `HoTMetaL' in the HoTMetaL Program Group. The icon must have a command line, consisting of the name and location of the executable file, followed by some command line "options" associated with it. Normally you won't have to worry about this because the installation program creates the command line for you. If you need to change something, note the following: + You can check the command line associated with this icon by using the Properties... command in the Program Manager File menu. + You can also change the HoTMetaL command line by using the Properties... command. + You can create a new program group using the New command in the Windows File menu, then add HoTMetaL to that group (also using the New command). + Alternatively, you could add HoTMetaL to an existing program group. When adding HoTMetaL to a group, associate it with a command line like c:\sqhm\sqhm.exe (Substitute the actual drive and directory for `c:\sqhm'. + An icon for the program item will be provided for you by HoTMetaL. Two other ways you can launch HoTMetaL from within a Windows session are: + Using the File Manager, move to the directory where you installed HoTMetaL. Now double-click on the file sqhm.exe. + Use the Run... command in the Windows Program Manager with an explicit command line such as: c:\sqhm\sqhm.exe 2.4. Associating HoTMetaL with HTML files If you want to associate HoTMetaL with your HTML files (thereby allowing you to invoke HoTMetaL by clicking on that file in the File Manager) do the following: * Choose the Associate... command in the File Manager's File menu. * In the File with Extension text box, enter `htm'. * In the Associate With text box, enter the command: c:\sqhm\sqhm.exe (Or click on Browse... and choose the program from a file chooser.) * Click on the OK manual. 2.5. Setting the HoTMetaL directory The directory where HoTMetaL is installed is referred to as "the HoTMetaL directory" throughout this documentation. If you are running a copy of the HoTMetaL executable file (sqhm.exe) that is not in the installation directory, it will not be able to find automatically the various auxiliary files and directories that it needs to run. In this situation you must inform HoTMetaL of the location of the HoTMetaL directory explicitly. There are two ways to do this: + Set the DOS environment variable called SQDIR to name the directory in which the software is installed. If the installation directory is c:\sqhm, for example, SQDIR should be set (from the DOS prompt) as follows: set SQDIR=c:\sqhm This setting could be added to your autoexec.bat file so that it will be executed every time your machine is booted. In any case, it must be done before you start up Windows. + Specify the HoTMetaL directory on the HoTMetaL command line. * Click once on the HoTMetaL icon. * Invoke the Properties... command in the Windows File menu. * A dialog box will appear. In the Command line text box in this dialog, add the -sqdir option followed by the name of the HoTMetaL directory. For example: d:\special\sqhm.exe -sqdir c:\sqhm If you set the HoTMetaL directory using both methods, the value that you specify on the command line will take precedence. If you will be running more than one copy of HoTMetaL, and will have a different HoTMetaL directory for each, you should specify the directories on the command line. 2.6. Creating and editing files This section gives the basic information needed to start editing files with HoTMetaL. 2.6.1. Creating a new file HoTMetaL comes up with a new, empty HTML document ready for you to use. You can also create a new file as follows: * Click on the New command in the File menu. HoTMetaL brings up a new, empty file. 2.6.2. Editing an existing HTML file If you already have an HTML file that you want to edit: * Click on the Open... command in the File menu. * In the dialog box that appears, choose the file that you want to edit. Once you've done this, HoTMetaL opens the file and you can begin editing. Some "legacy" HTML documents cannot be opened because they contain bad markup. See the section on the Open... command for information on strategies for dealing with this. 2.7. Configuring HoTMetaL There are many aspects of HoTMetaL's behavior that you can configure to your personal needs or those of your site. For example, you can control default options in the Find and Replace dialog box, set options for the Save command, and specify the locations of various auxiliary files. You can run HoTMetaL without any problems using the default configuration, but at some point you may prefer to customize. This will be particularly true if several people will be using HoTMetaL on the samePC. Throughout this manual you will see references to features that can be configured by setting a value for a particular configuration variable. These are set by editing files called configuration files, discussed below. The chapter The configuration mechanism lists and describes all of the configuration variables used by HoTMetaL. 2.7.1. Configuration files The default configuration files read by HoTMetaL are the file sqhm.ini located in the directory where HoTMetaL is installed and the file sqhm.ini in the Microsoft Windows directory (usually c:\windows). These files contain configuration parameters called configuration variables. Variables set in the file in the Windows directory take precedence. You can specify that different files are read by the configuration mechanism: see the chapter The configuration mechanism for details. If a particular variable (parameter) has a setting in more than one file, the value in the file that is read last will take precedence. If a variable is defined more than once in the same file, the value that appears last in that file will take precedence over values that appear earlier in the file. If a variable is not set in any configuration file, but is set in the environment, then the setting from the environment is used. If there is no setting in the configuration files or in the environment, then the built-in default value (if there is one) is used. If there is no default value, the variable is undefined. In summary, the value of a configuration variable is taken from the following sources, in the order given below: 1. The configuration files. 2. The environment. 3. The built-in default. 2.7.2. Configuration variables read on start-up! Configuration files (and configuration variables in the environment) are read by HoTMetaL on start-up, so the changes you make will take effect the next time you run HoTMetaL--they will have no effect on a currently-running HoTMetaL. If you need them to take effect immediately, you will have to exit HoTMetaL and restart it. 2.7.3. Setting parameters in the configuration files You do not need to change any configuration variables unless you wish to customize the HoTMetaL configuration. A variable is just a name that is assigned some value. You can change these variables by simply editing the configuration files, as appropriate, and making the desired changes. 2.7.3.1. Basic format for setting variables Variables are assigned values by putting lines of the following form in the configuration files: variable = value For example: undo_limit=50 (undo_limit is a configuration variable that specifies the number of successive commands that can be undone or reversed with HoTMetaL's Undo command. The default built in to HoTMetaL is 10; to raise this to 50, you would set the variable as in the example.) You may put spaces or tabs on either side of the equal sign for readability. Also, if you prefer, you may substitute a colon (:) for the equal sign: undo_limit:50 The effect is the same. You should not have any "white space" (spaces or tabs) at the end of the line. You should take care to use legal values for all the configuration variables. Otherwise, HoTMetaL may behave in unexpected ways. Further information on setting configuration variables can be found in the chapter The configuration mechanism. 2.8. Launching browsers and viewers Some HoTMetaL functionality (previewing the file with a browser and displaying graphics) relies on the existence of external applications. A configuration file (the file sqhm.ini in the Windows directory) tells HoTMetaL which programs to use to carry out these functions. The configuration variable html_browser in this configuration file specify the browser that will be used to preview your HTML files; view_gif and view_bmp specify the programs used to display GIF and BMP files. You must decide which programs you want to use for these purposes and then modify the values of the variables in the sqhm.ini file. You do this by opening the file with a text editor and making the desired changes. For example, if you want to use mosaic as your HTML browser you would put a line such as the following in sqhm.ini (this example uses a typical location for the mosaic.exe file--you must use the actual location on your PC): html_browser=c:\mosaic\mosaic.exe The view_gif and view_bmp variables should specify a graphics viewing program such as c:\windows\psp.exe (again, you must use the actual location on your PC). If you haven't already set these variables, you should do so now, because the tutorial below makes extensive use of the previewing feature. 2.9. Text and markup Like most electronic documents, an HTML file consists of text and markup. (Markup is special codes inside the file that indicate how part of the file is to be processed: for example, a word-processor file would contain markup indicating typographical features such as the font and font size for various parts of the document.) In an HTML file the markup consists primarily of elements. Elements normally consist of a start-tag that is placed at the beginning of a section of the text, and an end-tag that is placed at the end of that section of text. In HoTMetaL, when you insert an element in the document, you are actually positioning its start- and end-tags. When you want words and phrases to be considered as distinct elements, you surround them with tags. For example, a title in an HTML file would look like this: This is a title! As you will see, when you are editing documents with HoTMetaL, you don't have to deal with tags on this level: the start- and end-tags are represented on the screen by icons, and HoTMetaL will insert both tags for you when you select a portion of the text to be surrounded by an element. (In fact, HoTMetaL doesn't let you type tags literally--if you type the `<' character, HoTMetaL will replace it by a `character entity' icon that looks like this: lt.) The same file may look different when displayed with different browsers. When you are marking up a document in HTML format, you mark up parts of the document according to their function in the structure of the document. For example, there are different elements for headings, lists, list items, paragraphs, titles, and many other parts of a document's structure. One of the reasons for using HTML (and SGML) is that the files can be readily re-processed in a different format by other publishing, browsing, database, etc., applications. In addition to describing the structure of a document, some elements also describe the links to other documents that can be accessed from an HTML document. Because HTML documents are structured documents, the elements must be arranged according to specific rules: otherwise, the document is considered invalid. When you are using HoTMetaL, you don't have to keep track of these rules yourself--HoTMetaL does it for you. One of HoTMetaL's most important features is automatic rules checking, which ensures that you do not violate the required structure as you are creating a document. As well, when you open or save a document, HoTMetaL checks that the markup is correct and complete. Many HTML browsers have permitted a very loose, unstructured document format. Therefore, if you are editing existing HTML files, you may find that the structure that HoTMetaL imposes on documents is somewhat constraining. If you need to, you can relax these constraints using the Turn Rules Checking Off command in HoTMetaL's Special menu. Because there is an emerging trend toward browsers that require a stricter document structure, we believe that you will find it to your advantage to create all your new HTML documents with HoTMetaL's default rules in force. It will also be worthwhile to modify existing documents to conform to these rules. The document-structuring rules built in to HoTMetaL are designed to be flexible while at the same time maintaining a useful document structure. If an existing `legacy' document (one that was not created with HoTMetaL!) does not conform to these rules, HoTMetaL's Open... command will give you the opportunity to pass the document through a filter that will attempt to adjust the markup so that the document can be opened. You also have the choice of opening the document as a text document and editing it by hand. Once the errors are fixed, you can use the Interpret Document command to do the equivalent of Open... on the text file. 2.10. Templates The following document templates are supplied with HoTMetaL, in the folder Templates in the HoTMetaL folder. You can open these with the Open... command in the File menu, or, more conveniently, with the Open Template... command in the File menu (this command opens the correct folder automatically). + custreg.htm - example of a form. + deflist.htm - example of a definition list. + img.htm, imgs.htm - documents with images. + HomePage.htm - a Home Page. + h1.htm, h2.htm, h3.htm - examples of the use of heading elements. + lolist.htm, lulist.htm, solist.htm, sulist.htm - examples of lists. + paras.htm - a simple document with a few paragraphs. + Readme.htm - a list of templates. 2.11. A tutorial on creating documents with HoTMetaL If you're new to creating web (HTML) documents, you may want to use this short tutorial. The tutorial covers the following topics: + The basic document: titles, headers, and paragraphs. + Character formatting: formatting inline text + Block formatting + Lists: ordered and unordered lists + Links and URLs: anchors and images. The tutorials don't cover each topic exhaustively, but give you enough information for you to master a topic after obtaining additional details from the HTML Quick Reference which you'll find after the tutorial. The first part of the tutorial may be used as a "quick start" that shows you how to create a file with HoTMetaL. When you've finished that section, you can continue with the other sections or, if you feel comfortable using or experimenting with HTML on your own, you can skip over the rest of the tutorial and refer to the HTML Quick Reference section when you need to find out something about HTML. 2.11.1. Getting started: a basic document * Start up HoTMetaL. * Choose Insert Element... in the Markup menu, or type Ctrl-I at the keyboard. You will see a dialog box containing a list of elements that are valid at this point in the document. Elements are the "building blocks" of your document. Since the document is empty right now, any element is valid. However, we'll start by inserting the top-level element, which should be highlighted. You will probably find it convenient to pin this dialog on the screen, by clicking on the button in the upper left corner of the dialog box, and choosing the Pin command from the menu that appears. * Make sure that the Include Required Elements check box is turned on. * Double-click on the element HTML in the list of elements, or, if this element is already highlighted, click on the Insert Element button. HoTMetaL now inserts an HTML element by inserting start-tag HTML and end-tag HTML icons. (Sometimes tags are called "commands", but this isn't really accurate.) HTML surrounds all the other elements in the document. Notice that HoTMetaL has also inserted a HEAD element inside HTML, and a TITLE element inside HEAD. These elements are required in this context in the document. The insertion point is inside TITLE. The words "Document Title" are not part of the text of the document: this is a prefix which is for screen display only. * Inside the TITLE element, type a title for your sample document. When you display this document in a browser, the contents of this element will be displayed in the title bar. The main part of your document is the body, contained in the BODY element. * Move the insertion point to the right of the HEAD end-tag. * Insert a BODY element from the Insert Element dialog box (this is the only valid element at this point). If you look at the Insert Element dialog box, you'll notice that you have many choices of elements to insert. However, it's normal to start your document with a heading. Web documents have six levels of headings, represented by the elements H1 through H6. * Insert an H1 element. An H1 header will be used for major divisions in your document. * Type the following (or text of your choice) inside the H1 element: George Orwell Now you're ready to insert some text. * Move the insertion point to the right of the H1 end-tag. * Insert a P (paragraph) element. * Type some text such as the following: George Orwell is best-known as the author of "Animal Farm" and "1984", and these books gave the language the overused adjective "Orwellian". However, these works were written relatively late in his life, and followed an impressive body of work that includes accounts of his experiences as a soldier in the Spanish Civil War, and as a "down-and-out" tramp roaming the English countryside. You can begin smaller subdivisions of the document with lower-level (H2 through H6) headings. You can skip levels if you want, but your documents will usually look better if you don't. * After the P element, insert an H2 element. * Type the text: Early life and education * After the H2 element, insert a P element. * Type the text: Orwell, whose real name was Eric Arthur Blair, was born in India in 1903. He was brought to England, along with his mother and older sister, in 1907. His early education was at a village school, and later at a private preparatory school. At the age of 14 he won a scholarship to the prestigious Eton College. Now perhaps you'd like to see what this document will look like when it's published on the Web. But first, save the file: * Choose Save from the File menu, or typeCtrl-S at the keyboard. * Now, choose Preview from the File menu. HoTMetaL will invoke a browser displaying the file you're editing. (if no browser is launched, then you should check that the html_browser configuration variable points to a browser program.) As we suggested at the start of this section, you may wish to skip directly to the HTML Quick Reference, or continue with the extended tutorial. 2.11.2. Character formatting: Adding emphasis to inline text The techniques in this section are for formatting inline text--text that's embedded a paragraph or some other block of text. Techniques for formatting blocks are covered in the next section. In an HTML document, you add emphasis to a piece of text by surrounding it with an element. This is a little different from the approach of many word-processors, in which you would, for example, highlight a piece of text and choose a type style from a menu. * In the document you just created, highlight the words "Eric Arthur Blair". * Choose Surround... from the Markup menu, or type Ctrl-U at the keyboard. The list in the Surround dialog box gives all the elements that can surround the selection. * Double-click on the element I (italic) in the list. The selection is now surrounded by I and I tag icons, and, depending on which style sheet you've chosen, should be formatted in italic. In any case, a browser will format it in italic--you can use Preview to try this out. Of course, you don't always have to surround the text after you've typed it--you can insert an I element with Insert Element... and just type the text between the tags. For more information on character formatting, see the section Character formatting in the HTML Quick Reference. 2.11.3. Formatting blocks of text There are several elements that you can use to surround parts of your document that require special formatting. For example, suppose you wish to add a block quote to the sample document you created above: * Move the insertion point to the right of the last P end-tag. * Choose Insert Element... in the Markup menu, or type Ctrl-I at the keyboard. * Insert a BLOCKQUOTE element. * Type the text: Orwell portrayed his prep school days in harsh terms in the essay "Such, Such Were the Joys...". This may have been the result of interpreting his early experiences in the light of his later political consciousness. (B. R. Jones) Notice that the text is indented slightly to set off the quotation. A browser will display a block quote with similar special formatting. For more information on block formatting, see the section Block formatting in the HTML Quick Reference. 2.11.4. Lists You can insert five different types of lists in your document. 2.11.4.1. Ordered (numbered) lists Ordered lists are lists with numbered items. You don't have to add the numbers yourself--a browser will add these for you. * Move the insertion point to the right of the BLOCKQUOTE end-tag in the sample document. * Insert an H2 element. * Type: Orwell's Four Great Motives for Writing * Move the insertion point to the right of the H2 end-tag. * Insert an OL (ordered list) element. When you do this, HoTMetaL automatically inserts an LI (list item) element. With one exception, all lists consist of one or more LIs. * Inside the LI element, type: Sheer egoism * Make sure the insertion point is just to the right of the LI end-tag. * Insert a new LI element. * Inside the new LI, type: Aesthetic enthusiasm * Insert another LI element after the last one. * Type: Historical impulse * Insert another LI element after the last one. * Type: Political purpose To really see how ordered lists work, you should preview the document: * Save the document. * Choose Preview from the File menu. As you can see, the browser has inserted the list numbers automatically. 2.11.4.2. Unordered lists An unordered list is one whose items aren't numbered, but instead start with bullets of some kind. Actually there are several kinds of unordered lists available to you: here we'll use the most common and general-purpose list element, UL (unordered list). In this section you'll also learn a new markup command. * Move the insertion point to a position between the OL start-tag and the first LI start-tag. * Choose Change... from the Markup menu, or type Ctrl-L at the keyboard. The dialog box that appears is similar to the one you saw when you used the Insert Element... and Surround... markup commands. This time the list contains all the elements that can validly replace the current element. (The current element is OL.) Not surprising, your choices are all types of lists. * Double click on UL in the list of elements. The OL start- and end-tags have changed to UL tags. * Save the file. * Choose Preview from the File menu, or type Ctrl-M at the keyboard. The browser now displays the list items with bullets rather than numbers. You can nest lists by inserting a UL, OL, etc., inside a list item (LI). Some browsers will take account of this by changing the list bullet for the nested list. For more information on lists, see the section Lists in the HTML quick reference. To see examples of lists, you can use the Open Template... command to open the templates lolist.htm, lulist.htm, solist.htm, and sulist.htm. 2.11.5. Links and URLs It is normal for HTML documents to contain links to other documents, which can be located anywhere on the WWW. These links are provided by Universal Resource Locators (URLs), which name the location and filename of a document, and the protocol used to access it. 2.11.5.1. Anchors When you want to create "hot text" that someone can click on in a browser and cause a document to be accessed, you use an "anchor" (A) element. * Move the insertion point to a position just before the BODY end-tag. * Type the text: See also the * Insert an A element. * Inside the A, type the text: bibliography The word "bibliography" is hot text. In a browser it will be displayed in a different color than surrounding text. The second step in creating an anchor is creating the URL. A URL is not part of the content of the element, like hot text is. A URL is an attribute of the element. * Make sure the insertion point is inside the A element. * Choose Edit SGML Attributes... from the Markup menu. This gives you a dialog box with entries (text boxes) for each of the attributes. Right now you need to work with only one of these. * In the text box labelled HREF, type the following (without any spaces between the parts): 1. The characters "file:///". 2. The name of the drive (without the colon) that the HoTMetaL software is located on. 3. A vertical bar, `|'. 4. The directory (full path) that the HoTMetaL software is located in, but instead of typing `\' (backslash) between the directories, as you normally do in Windows, type `/' (slash). 5. The filename "works.htm". What you type should look something like this: file:///c|/sqhm/works.htm The word "file" is a protocol (also called a "scheme"), which describes how the file referred to in the URL will be accessed by a web browser. You are using the file protocol because the file you're going to choose is on your local filesystem. If the document were on a web server, you would choose the protocol http. The directory component of the URL is expressed in the "standard" format, which requires that the colon (:) be replaced by a vertical bar, and that directories be separated by slashes. * Click on the Apply button. What this all means is, when someone clicks on the hot text (the word "bibliography") in a browser, the browser will attempt to locate the file(works.htm) referred to in the URL. To see how this works, you should view the document in a browser: * Save the file. * Choose Preview from the File menu, or typeCtrl-M at the keyboard. * In the browser, double-click on the word "bibliography". The browser will now display the fileworks.htm. 2.11.5.2. Links within the same document It's possible to make a link between two anchors in the same document. Then, when you click on one of the anchors (call it the "source") the browser window will scroll to the location of the other anchor (the "destination"). * Move the insertion point to a position just before the first P end-tag. * Choose Split from the Markup menu, or typeCtrl-P at the keyboard. * In the new P element, type: One of his well-known essays is * Insert an A element. * Type: Why I Write * Make sure the insertion point is inside the anchor you just created. * Choose Edit SGML Attributes... from the Markup menu. The dialog box that appears contains text boxes for each of the elements attributes, labeled with the attribute name. * In the HREF text box, type: #WHY You have just set up the "source" anchor. This is the URL for this anchor, even though it doesn't look like the URL you created in a previous part of this tutorial. Now you have to set up the "destination" anchor: * Highlight the words "Four Great Motives" in the second H2 element. * Use the Surround... command to surround this text with an A element. In this instance you're not going to create a URL for the anchor, rather, you're going to give this anchor a "name" by editing one of its attributes. * Make sure the insertion point is inside the anchor you just created. * Choose Edit SGML Attributes... from the Markup menu. * In the NAME text box, type: WHY * Click on the OK button. Now you're ready to see the effect of what you've just done. * Save the file. * Choose Preview from the File menu, or typeCtrl-M at the keyboard. * If both of the anchors you just created are visible, resize the browser window so that you can see only the first one. * In the browser, double-click on the words "Why I Write". The browser window will now scroll so that the location of the "destination" anchor is visible. In general, you can set up a "source" and "destination" anchor pair by setting the NAME attribute of the destination anchor to `string' and setting the HREF attribute (i.e., the URL) of the source anchor to `#string'. This sets up a one-way link. You can set up a two-way link by editing the two anchors so that each one's NAME attribute corresponds to the other's HREF. 2.11.5.3. Images Web documents often include graphical images. Images are inserted in a document using an element that is similar to the A element. * Click on the View menu. * If it contains the command Show Inline Images, choose this command. If it contains the command Hide Inline Images, do nothing. * Move the insertion point to a position just to the right of the H1 end-tag. * Insert an IMG (image) element. (If this element is not visible in the Insert Element dialog box, just type the letter `i' and the list will scroll to the proper position.) * Choose Edit SGML Attributes... from the Markup menu. Now you are going to give the HREF attribute of the IMG element a value very similar to the first URL you created in the section on anchors. It will be the same except for the filename, which in this case is "author.gif". The URL will look something like this: file:///c|sqhm/author.gif * Click on the Apply button. When you do this, a graphical image will be displayed inline, in the HoTMetaL document window. (This is not really George Orwell, but another writer whose work you know if you're reading this manual.) The inline image will be displayed in the browser, too. * Save the file. * Choose Preview from the File menu, or typeCtrl-M at the keyboard. See the section Link elements in the HTML quick reference for more information on images; in particular, you will find information on "hot images" and images with hot spots. 2.11.6. Forms There are certain elements that a browser will display as graphical widgets, such as text fields or pop-up menus, that can accept input from a user. A form in an HTML document is a set of such elements that let the user enter some information and then call a program, located on a web server, that processes the information. For example, you could create a form that lets a user order a product that you're selling: you can set up the form so that when the user clicks on a "submit" button, the order is sent to your order-processing program. To implement this, you have to: + Create the form(s). + Install on your server the program that will process the form's data. The second of these two steps is beyond the scope of HoTMetaL. You will have to obtain supplementary documentation that explains this mechanism, which is known as the CGI (Common Gateway Interface). If you open the file faq.htm in the HoTMetaL folder you will find a reference to a document on this topic. This tutorial explains how to properly set up a sample form. We've noticed that many browsers still have bugs in their support for forms. If something that you create in this tutorial doesn't look the way it should when you display it with your favorite browser, the problem may be with the browser. We suggest that for this exercise you create a new HTML document. * Choose New from the File menu, or typeCtrl-N at the keyboard. * Enter the HTML, HEAD, TITLE, and BODY elements as you've already learned to do. * Now insert an H1 element, and type: Buy my book! * Insert a P element, and type: Do I have a deal for you! Just click on the "Submit" button in the form below to order any or all of these best-sellers at a fraction of the regular cost! (N.B.: This is not a tutorial on sales pitches!) 2.11.6.1. Actions Now you're ready to start constructing a form. * Insert a FORM element after the P element. * With the insertion point inside the FORM element, choose Edit SGML Attributes... in the Markup menu. This gives you a dialog box in which you will give a value for the ACTION attribute. * In the ACTION text box, type: http://www.sq.com/cgi-bin/quagmire The "action" you've just specified refers to a program, located on SoftQuad's HTTP server, that can process the data entered in the form. At the end of the tutorial, you can submit the form to this program. In a "real-life" situation, you would probably specify a program on your own server, though in fact you can specify programs located anywhere on the Web. * Set the attribute called METHOD to the value "GET". * Click on the Apply button. Another action that you can use is mailto: this causes the form to be e-mailed to a specified address. (You can try this later: for the purpose of this tutorial, please use the action described above.) To make use of mailto: * Inside the FORM element, choose Edit SGML Attributes... in the Markup menu. * Set the ACTION attribute to the string "mailto:" followed by the e-mail address to which you want the form sent, e.g., mailto:charles@windsor.org * Set the METHOD attribute to "POST". Some browsers do not support mailto. Also, in order for this feature to work if your system is behind a firewall, you may need to configure your browser to use the correct proxy server. 2.11.6.2. Creating a text box Now you'll enter the first element that generates a graphical widget in the browser: * Enter a P element and type: Name: * Inside the paragraph, enter an INPUT element. You can now preview the file to see what this looks like in a browser: * Save the file. * Choose Preview from the File menu, or type Ctrl-M at the keyboard. Notice that the browser has placed a text box next to the word "Name:". You're not done with this INPUT element yet. * Move the insertion point inside the INPUT element. * Choose the Edit SGML Attributes... command from the Markup menu, or type Ctrl-] at the keyboard. This brings up a dialog box that lets you edit the attributes of the current element. * In the text box for the attribute NAME, type: cust-name This value is used when the browser sends the form's data to the server, in order to identify which text box, drop-down list box, etc., a particular piece of data came from. Another attribute, SIZE, is used if you want to specify the text box's length in characters. 2.11.6.3. Entering several lines of text A text box in a form just lets you enter one line of text. If you need to allow your users to enter several lines of text at once (to enter an address, for example), you should use the TEXTAREA element. * Insert a new P element and type: Address: * After the text, insert a TEXTAREA element. * Choose the Edit SGML Attributes... command from the Markup menu, or type Ctrl-] at the keyboard. * Enter the following values for three of this element's attributes: NAME: cust_addr ROWS: 5 COLS: 40 ROWS and COLS specify the dimensions of the widget: 5 lines deep and 40 characters wide. * Click on the Apply button. Note: if you want a TEXTAREA to contain some default text, enter it between the start- and end-tags. Now you may want to see how the browser renders this object: * Save the file. * Choose Preview from the File menu, or type Ctrl-M at the keyboard. The browser generates a multi-line field, which may also have scroll bars. 2.11.6.4. Presenting a list of choices Sometimes you will want the user to make one choice from a list of choices. In this example you'll see how to represent this with a drop-down list box. * Insert a new P element, and type: Credit Card: * After the text, insert a SELECT element. HoTMetaL will ask you if you want to edit the attributes of this element. * Click on the Stop and edit button. * Enter "card-name" for the NAME attribute, and `1' for the SIZE attribute. * Click on the Apply button. * Inside the SELECT element, insert an OPTION element, and type: Visa The OPTION element represents one choice in the a drop-down list box. The text you typed inside the element is a label that will appear in the list box. * Insert two more OPTION elements after this one, containing the text "MasterCard" and "Amex", respectively. To see what this looks like in the browser: * Save the file. * Choose Preview from the File menu, or type Ctrl-M at the keyboard. Notice that the text you typed inside each of the OPTION elements appears as labels on the a drop-down list box. If you wanted, you could have represented this list of choices as a scrollable list rather than a a drop-down list box. To do this, you would set the SIZE attribute to 2 or greater; this value would specify how many list items are shown at a time. If you want to be able to choose more than one item from this kind of list, set the MULTIPLE attribute to "MULTIPLE". Just to complete this section of the form: * Insert a new P element after the last one, and type: Card number * Insert an INPUT element. * Choose Edit SGML Attributes... from the Markup menu, or type Ctrl-] at the keyboard. * Set the NAME attribute to "card-num". * Click on the Apply button. 2.11.6.5. Check boxes So far you have used the INPUT element only to represent text boxes. Actually, this element can be used for a variety of purposes. One of these is representing check boxes: you would use this kind of box if you wanted the user to make a "yes/no" choice. (This is different from aoption button (see below), which you would use when you wanted the user to choose one from a group of choices.) * Insert a new P element after the last one, and type: Check one or more titles: * Insert a new P element after the last one, and type: The Dentistry of Frederic Chopin * Insert an INPUT element. * Choose Edit SGML Attributes... from the Markup menu, or type Ctrl-] at the keyboard. * Set the TYPE attribute to "CHECKBOX". (This is the attribute value that tells the browser that it should generate a check box.) * Set the NAME attribute to "chopin". * Click on the Apply button. Now add two more titles in the same way: * Insert a new P element after the last one, and type: Motors and Such by Eddy Schneider * Insert an INPUT element. * Set the TYPE attribute to "CHECKBOX" and the NAME attribute to "motors". * Insert a new P element after the last one, and type: HTML for Travellers * Insert an INPUT element. * Set the TYPE attribute to "CHECKBOX" and the NAME attribute to "html". To see what this looks like in the browser: * Save the file. * Choose Preview from the File menu, or type Ctrl-M at the keyboard. Try clicking on the buttons with the mouse. You can turn on all, any, or none of the buttons. 2.11.6.6. Radio buttons As we said above, you can also use the INPUT element to represent radio buttons. A group of radio buttons lets the user make one (and only one) choice from a group of choices. * Insert a new paragraph after the last one and type: Preferred language: * Insert a new paragraph after the last one. * Insert an INPUT element. * Choose Edit SGML Attributes... from the Markup menu, or type Ctrl-] at the keyboard. * Set the following attribute values: NAME: language VALUE: english TYPE: RADIO CHECKED: CHECKED * Move the insertion point to the right of the INPUT end-tag and type: English Now add two more choices in the same way (keep all three choices in the same paragraph): * Insert an INPUT element. * Set the following attribute values: NAME: language VALUE: french TYPE: RADIO * Move the insertion point to the right of the INPUT end-tag and type: French * Insert an INPUT element. * Set the following attribute values: NAME: language VALUE: spanish TYPE: RADIO * Move the insertion point to the right of the INPUT end-tag and type: Spanish Notice the following things about the attribute values you've just entered: 1. Each TYPE attribute is set to "RADIO". This tells the browser to generate a radio button. 2. Each NAME attribute has the same value, in this case, "language". This causes all three radio buttons to be in the same group, which means that the browser will allow only one of these three to be checked at once. If the form contains another group of radio buttons, the NAME attribute for all of its members must be the same, but different from the value for the current group. 3. The value of the VALUE attribute is sent to the server if the corresponding button is turned on when you submit the form, thus telling the server which button in this group was turned on. 4. The first INPUT element in this group has the CHECKED attribute set to "CHECKED". This tells the browser that this button should be turned on by default when the form is first displayed. To see what this looks like in the browser: * Save the file. * Choose Preview from the File menu, or type Ctrl-M at the keyboard. Try clicking on the buttons with the mouse. You can turn on only one of the radio buttons at a time. The button labeled "English" is initially turned on by default. 2.11.6.7. Reset You can use the INPUT element to generate a button that restores all the form's controls(text boxes, radio buttons, etc.) to their default values: * Insert a new P element after the last one. * Insert an INPUT element. * Choose Edit SGML Attributes... from the Markup menu, or type Ctrl-] at the keyboard. * Set the following attribute values: TYPE: RESET VALUE: "Reset defaults" To see what this looks like in the browser: * Save the file. * Choose Preview from the File menu, or type Ctrl-M at the keyboard. * Enter some data in the form. * Click on the Reset defaults button in the form. The form's controls revert to their default values. The text boxes are all blank and the check boxes are turned off. The radio button labeled "English" will be turned on. 2.11.6.8. Submitting the form Your form is almost complete. All you need to do is create a button that causes the browser to submit the form. * Next to the INPUT element for the reset button, insert another INPUT element. * Choose Edit SGML Attributes... from the Markup menu, or type Ctrl-] at the keyboard. * Set the following attribute values: TYPE: SUBMIT VALUE: "Submit order" To see what this looks like in the browser: * Save the file. * Choose Preview from the File menu, or type Ctrl-M at the keyboard. * Enter some data in the form. (Don't enter a real credit card number!) * Click on the Submit order button in the form. The form will now be submitted to a program on SoftQuad's web server. This program doesn't actually process an order, it just echoes back the information that the browser sent it. This information will appear in the browser window: you can return to the form by clicking on the button that takes you to the previous document. The information is presented in pairs containing a "name" (corresponding to the NAME attribute of the text box, check box, etc.) and a "value" (for text boxes or "text areas", this will be the data you typed in; for check boxes the value "on" is submitted--check boxes that aren't turned on are ignored; for radio buttons the value of the VALUE attribute is sent). You may notice a couple of unusual things about the format of the text: spaces are replaced by a `+' sign, and some special characters (notably newline, `=', and `&') are replaced by `%nn', where the n's are digits from 0-9 and/or letters between `A' and `F'. This is the standard form that browsers use for submitting data to the server. 2.12. HTML quick reference The authoritative source of information on the structure of HTML documents is the document HyperText Markup Language (HTML) Version 2.0. This section provides a short summary of this material. The rules governing the HTML format are quite flexible, and furthermore HoTMetaL will guide you through the document structure: therefore, the approach followed here will not be to enumerate all the possible combinations of elements. Rather, an overview of the structure will be presented, together with a discussion of the different groups of elements (emphasis, links, lists, etc.). 2.12.1. Overview + An element called HTML surrounds the whole document. + This element contains two sub-elements, HEAD and BODY. These elements are required. + HEAD has sub-elements that define header material: - TITLE: document title. This element is required. - BASE: can be used to record the document's URL. The URL recorded here may be used to resolve a "partial URL", or used if the document is accessed "out of context". - ISINDEX: indicates to the browser that the document is an index document. This is used only if the document is on a server that does indexing. - LINK: indicates a relationship between this document and some other object. - META: gives information that appears in HTTP headers. - NEXTID: used to generate a unique identifier. + Inside the BODY element, heading elements (H1 through H6) can be used to delimit major divisions of the document (headings are not mandatory, however). Headings are permitted to appear in any order, but you will obtain the best results when your documents are displayed in a browser if you follow these guidelines: - H1 should be used as the highest level of heading, H2 as the next highest, and so forth. - You should not skip heading levels: e.g., an H3 should not appear after an H1, unless there is an H2 between them. 2.12.2. Block formatting + The major divisions of a document body's structure comprise the following elements: - ADDRESS: if you want to include the address of the author of the document, enter it inside this element. - BLOCKQUOTE: used for quotes from another source, requiring special block-style formatting. - CODE: code samples. - P: paragraphs. - PRE: pre-formatted text. You would use this text when you want the browser to use the same line breaks and spacing that you entered in the document. The text will be formatted by a browser using a fixed-width typewriter font. - DL, DIR, MENU, OL, UL: list elements (see Lists, below). 2.12.3. Character formatting The following elements are used primarily for formatting inline text: + B: bold. + I: italic. + EM: browsers usually represent this element in italic. + STRONG: browsers usually represent this element in bold. + TT: characters inside this element are formatted with a fixed-width typewriter font such as Courier. + SAMP: literal characters. 2.12.3.1. Line breaks If you want to force a browser to break the current line in the text, insert a BR element. You can't type inside this element: it just causes a line break. 2.12.3.2. Horizontal lines To cause the browser to print a horizontal line (rule) in your document, insert an HR element. HoTMetaL will display a line in your document, but individual browsers may print lines of different widths and lengths. 2.12.4. List elements HTML supplies five list elements. With the exception of DL, list elements are composed of one or more LI (list item) elements. You can nest lists by inserting a UL, OL, etc., inside a list item (LI). + OL: ordered list. Items in this list are numbered automatically by the browser. The numbering will reflect nesting levels. + UL: unordered list. Items in this list are prefaced by a list mark such as a bullet. Browsers will usually vary the list mark to take account of nesting. + DIR: directory list. This is an unordered list. Each LI element in this kind of list should no longer than 24 characters. + MENU: menu list. This is an unordered list. Each LI element in this kind of list should be no longer than one line. + DL: list of definitions. This is an unordered list. This kind of list is different from the others. Each "item" in this kind of list consists of one or more terms (DT elements), followed by a definition (DD element). 2.12.5. Link elements It is normal for HTML documents to contain links to other documents, which can be located anywhere on the WWW. These links are provided by Universal Resource Locators (URLs), which are identifiers that name the location and filename of a document, and the protocol used to access it. The following elements represent links to other documents: + A: anchor. The HREF attribute of this element represents a URL. If this attribute has a value, the content of the element will be highlighted when the document is displayed in a browser window, and clicking on this content will cause the browser to attempt to open the file specified by the URL. + IMG: image. This element represents a graphic image. It is typically used for inline images--you should be aware that some browsers may not be able to display such images. (In this case, the text, if there is any, given in the ALT attribute may be shown.) The SRC attribute represents a URL. See the sections on the Show Image and Show Inline Image commands in the View menu for information on displaying images in HoTMetaL. HoTMetaL has three commands for working with URLs: + Edit SGML Attributes... in the Markup menu provides a mechanism for editing the URL (if there is one) in the current element. See the tutorial section for an example of using this command. + Publish... in the File menu is used if you want to change the URLs in the document from identifiers that refer to files on your local system to identifiers that refer to publicly-available files on one or more WWW servers. + Show Link and Context View in the View menu is used to display the URL (if there is one) in the current element. 2.12.5.1. Links within the same document This topic is covered in an extended example in the tutorial section. In general, you can set up a "source" and "destination" anchor pair by setting the NAME attribute of the destination anchor to `string' and setting the HREF attribute (i.e., the URL) of the source anchor to `#string'. This sets up a one-way link. You can set up a two-way link by editing the two anchors so that each one's NAME attribute corresponds to the other's URL. 2.12.5.2. `Hot images' A `hot image' is used like an anchor--when you click on the image, the browser retrieves a document. This is very easy to accomplish: you just need to insert an IMG element inside an A element. Each element will have a URL: the IMG's URL locates the image, and the A's URL locates the file that is retrieved when you click on the image. 2.12.5.3. Images with hot spots Sometimes you will see images that have several "hot spots" that you can click on and cause different documents to be retrieved. This is accomplished by means of a clickable image map, a file that tells the browser where the hot spots are. To prepare such a file, you'll need other tools besides HoTMetaL, and so we won't discuss the procedure here. Rather, you should retrieve the document "Overview on using Clickable Image Maps " by opening the file faq.htm, located in the HoTMetaL installation folder, with a browser and clicking on the appropriate anchor. 2.12.6. Forms The following elements are used to construct forms that the user can fill in and submit (e.g., via e-mail). When your document is browsed, the browser will generate the appropriate graphical widgets. + FORM: the top-level element for a form. + INPUT: generates a text field, button, radio button, or check box. + SELECT: represents a group of choices that a user can make. Generates a pop-up menu or scrollable list. + OPTION: one choice in a SELECT group. + TEXTAREA: generates a field that allows the user to enter several lines of text. For more information on forms, see the tutorial on forms in this chapter. You can also retrieve the document "Information on setting up form functionality" by opening the file faq.htm, located in the HoTMetaL installation folder, with a browser and clicking on the appropriate anchor. To see an example of a form, use Open Template... to open the template custreg.htm. 2.12.7. Other elements The elements in this section do not fit into the categories described above. + CITE: represents a document citation. + KBD: used to display text that a user would enter at the keyboard. (This would be used in technical manuals, for example: it is not similar to an element such as INPUT, used in forms.) + VAR: represents a variable name. 2.12.8. Obsolete elements The elements PLAINTEXT, XMP, and LISTING are obsolete and are supported in this release of HoTMetaL only for compatibility with older documents. Using these elements in new content is not recommended. XMP and LISTING should be replaced by PRE. The obsolete elements COMMENT and HP are not supported. 2.12.9. Proposed elements The proposed elements DFN, STRIKE, and U are not supported by HoTMetaL. 2.13. If you see something you like... If you see a web page that contains a typographical effect, form, etc., that you like, then the easiest way of achieving the same thing yourself is to save the file with the browser (make sure you save it in HTML format) and then open it with HoTMetaL. 2.14. For further information... The file faq.htm in the HoTMetaL installation folder contains titles and URLs for documents that contain information on HTML usage. Open this file with a browser and retrieve the documents that you're interested in. A number of HTML tutorials, of varying quality, are usually available on the web. The relevant Usenet newsgroups (those in the comp.infosystems.www hierarchy) are also a source of information. 2.15. The structure of HTML documents HoTMetaL will guide you through the structure of an HTML document, but here is a short description of the format. + An element called HTML surrounds the whole document. + This element contains two sub-elements, HEAD and BODY. + HEAD has sub-elements that define header material, such as TITLE (document title) and META (gives information that appears in HTTP headers). Each of these elements is optional. + BODY consists of a PROLOGUE, six levels of "division" elements (DIV1-DIV6), followed by an EPILOGUE element. All of these elements are optional. + The division elements are arranged as follows: zero or more DIV6 elements, followed by zero or more DIV5 elements, and so forth, ending with zero or more DIV1 elements. + DIV6 is the "lowest" of the division levels in that it cannot contain instances of any of the other division elements. DIV1 is the highest level--it can contain any of the other division elements. In general, a division element can contain any division element at a lower level than itself. + Division elements start with a header element (H1 for DIV1 elements, H2 for DIV2 elements, and so forth. + Division elements, as well as the EPILOGUE and PROLOGUE, can contain paragraphs (P), lists (OL, DL, UL), horizontal rules, and addresses. + Paragraphs can contain annotations, links, quotes, citations, emphasis, examples, etc. + Lists consist of list items (LI), which can contain paragraphs, lists, horizontal rules, and addresses. 2.15.1. Rules files The rules that determine how elements can be arranged in an SGML file are described by a set of declarations collectively known as a document type declaration, or DTD. HTML files are no exception to this. HoTMetaL reads a DTD in a special, binary form called a rules files which contains the same information as the DTD but in a different format, one which is more efficient for HoTMetaL to read. It is not necessary for you to know more details about DTDs and rules files. You just need to be aware that HoTMetaL uses a rules file called html.mtl: this file is located in a directory called rules in the HoTMetaL directory. If you are interested in seeing the DTD for HTML files, look at the file html.mtl in the dtds directory underneath the HoTMetaL directory. 2.16. Commands for inserting markup The most common operations you will carry out in order to add or change markup are: + The Insert Element... command in the Markup menu inserts a new, empty element in which you can type text or insert other elements. + The Surround... command in the Markup menu lets you surround a selection with an element: if some part of the document should be contained in a particular element, then you can highlight that portion and select this command in order to choose an element to surround it with. + The Change... command in the Markup menu lets you change the markup: if you want to tag part of the document with a different element you can select this command to get a list of valid elements to replace the current element. 2.17. Screen formatting HoTMetaL provides screen-formatting capabilities that facilitate the document creation process by allowing you to assign distinctive styles to the elements in your document. The purpose of these formatting features is only to improve the appearance of the document during the editing process. The formatting that you set with HoTMetaL does not affect how browsers such as Mosaic format the document. Because HTML files are structured documents, setting a style for an element means setting it for all elements of the same type. The following kinds of typographical properties can be set: + Character-based properties: font family, font size, font style, line height, justification, fill mode, and format type. All of these properties are set using the Character... command. (Font style allows you to adjust the font by making it bold, superscript, etc.; the fill mode determines how carriage returns are treated--in fill mode, they are treated like spaces, but in no fill mode they cause a line break; format type lets you choose whether an element appears inline or starts on a new line.) + Separation: using the Separation... command, you can set off elements by adding space on top and on bottom. This command also lets you cause an element to be formatted as if it started with a tab. 2.17.1. Styles HoTMetaL stores its formatting information in files called styles files: these contain the formatting information set with the Character... and Separation... commands. HoTMetaL maintains two kinds of styles files. There is one default styles file, which is used whenever a file is created or opened with HoTMetaL. This is a binary file called html.stl. When an HoTMetaL file is created or opened, HoTMetaL looks for this styles file in the styles path, that is, the set of directories named by the styles_path configuration variable. If it finds the styles file, then the formatting information contained in that file is used for the current HoTMetaL file. If the styles file is not found, then a new styles file, containing the default formatting information, is created in the first directory in the styles path. Whenever the current HoTMetaL document is saved, this styles file is updated with whatever formatting parameters are in effect for the document. HoTMetaL also uses styles files in text format. These styles file are loaded using the Load Styles... command. You can switch styles in the middle of a HoTMetaL session by choosing a new text styles file with this command. The formatting information from a text styles file will not be written to the default (binary) style unless the current file is saved. Text styles files are created using the Save Styles... command. You can maintain as many text styles files as you wish. 2.17.2. Displaying images The Show Image command in the View menu lets you launch an external application (which you can choose by means of a configuration variable) to display a graphical image. By default, GIF images are displayed inline (in the HoTMetaL document window). See the Show/Hide Inline Images command in the View menu for more information 2.17.3. Previewing the document In order to preview the current document, you can invoke a browser of your choice from within HoTMetaL. To do this, just invoke the Preview command in the File menu. In order for this to work, you must specify a browser in the HoTMetaL preferences file. See the section on this command for more information. 2.17.4. Displaying icons Using the Show/Hide Tags command in the View menu, you can cause the special character icons and the tag icons that represent elements to be visible or invisible. 2.17.5. Displaying a document outline The command Show Structure View in the View menu displays a nested outline view of the document. You can cut, copy, paste, and navigate in this outline. For more information, see this command's documentation in the chapter The View menu. 2.17.6. Newlines Although pressing the Return or Enter key will put a "newline" into the file, Mosaic and other browsers follow the SGML whitespace rules, and therefore will ignore new line characters in some circumstances. 2.18. Attributes Elements can have content (text and sub-elements contained in the element) and attributes. An attribute is a piece of information about the element which does not appear in the content of the element. Some common uses for attributes are: to represent a link (URL); naming an image file; choosing different types of graphical controls for an on-line form. 2.18.1. Viewing attribute values There are a number of ways of telling whether or not an element has attributes, and of seeing what the attribute values are. + If the current element has one or more attributes, then the Edit SGML Attributes... command in the Markup menu is activated (whether or not the attributes have been given values). If you invoke this command, you can see what the attribute values are and also edit the values. + The context view, which is displayed by invoking the Show Link and Context View command in the View menu, displays the sequence of elements that contain the current element. It also displays the attribute values for any elements in the sequence that have attributes. + The styles file supplied with HoTMetaL allows you to display attribute values inline, as prefixes displayed just to the right of the start-tag icon. 2.18.2. Editing attributes Attribute values may be inserted or changed using the Edit SGML Attributes... command in the Markup menu. When you invoke this command, you will get a dialog box that contains a line for each attribute of the current element. Each line contains the attribute name followed by either a text box or a drop-down list box, depending on what kind of value the rules file says the attribute must have. The attribute value may be text (which could be subject to restrictions such as the length of the text or first character in the text), or a selection from a list of values. 2.19. Netscape support We have included a rules file that allows you to use the extended features (as best as we can determine them) supported by the Netscape browser. You must modify the configuration file to name the alternate rules file if you want to use these features. * Edit the configuration file, and locate the line assigning a value to the rules_file variable. * Put a `#' character at the beginning of this line. This "comments it out" so that HoTMetaL will ignore it. * Now insert the line: rules_file=html-net.mtl * Save the file and restart HoTMetaL. If you want to restore the previous rules, "comment out" the line you just inserted and remove the `#' from the original line. You should be aware that the Netscape extensions to HTML are not part of the HTML 2.0 specification. Web users viewing documents made with this alternate rules file will not notice the effects of the extensions when they view the file with a browser other than Netscape (e.g., text in the BLINK element will not blink, an IMG element with the attribute ALIGN=RIGHT will not align the image to the right, etc.) For HTML markup that conforms to the HTML 2.0 specification, you should continue to use the default rules file (html.mtl). HTML markup created with this rules file can still be used with Netscape (but will not take advantage of the extended features). 3. The File menu The File menu contains commands for creating, opening, closing, and saving files edited with HoTMetaL, previewing the current document with a browser, and modifying URLs. 3.1. New When you invoke this command a new, empty HoTMetaL document is displayed ina document window. 3.2. Open... Opens a previously saved file. HoTMetaL presents you with a dialog box allowing you to open a file. The dialog box is called a file selection dialog; a similar dialog box appears when you select the Save As... command. The structure and function of the file selection dialog box for the Open... command is explained here. The dialog box has several parts: + A drop-down list box labeled List Files of Type. This list box lets you choose whether to display files with the default file extension (.htm) or display all files in the current directory. + a text box labeled File Name This text box can contain a relative or absolute path name, which terminates in a file name or directory name, and can optionally start with a drive name. A file name (which may contain an extension) can contain the following "wildcard" (special) characters: + * (asterisk): matches any sequence of characters in a file name + ? (question mark): matches any single character in a file name Such a pattern containing wildcard characters is used to filter the file names displayed in the list box directly below. You can type a pattern in the box directly or choose it from the List Files of Type list. If the File Name box contains a path name that ends in a file name without wildcard characters, clicking on OK will cause that file to be opened. + an information field labeled Directories The current directory (including the drive name) appears underneath the label. The default directory is the one specified first by the import_path configuration variable. + a list box underneath the File Name text box This list contains the files in the current directory that match the pattern in the File Name box. The list of files is updated whenever a new directory is chosen, and when you click on the OK button. Clicking once on a file in this list causes the name to go in the File Name box. Double-clicking causes the file to be opened. This has the same effect as clicking once on the file name and then clicking on the OK button. + a list box, on the right side of the dialog, underneath the Directories information field This box allows you to navigate in the directory structure of a drive by double-clicking on the directories shown in the list. The top level "directory" displayed is the current drive; if you double-click on this directory, its subdirectories are displayed, slightly indented to indicate the nesting relationship. If you click on one of these directories, its subdirectories will be displayed, and so forth. At any particular time the list will display the sequence of directories that you have navigated along, ending with the subdirectories of the last directory you selected. + A drop-down list box labeled Drives. This allows you to choose which drive to navigate. By pressing Tab or Shift-Tab you can make the File Name box, the list of directories, the list of files, or either of the buttons the active item in the dialog box. When either of the lists is active, you can select a list item by pressing repeatedly on the first letter of the item until it is selected. When the File Name box is active, you can enter text in it. In summary: you may select a directory from which a file may be opened by using the list of directories, or by typing the path name in the File Name text box. You may choose a file by doing one of the following: + double-clicking in the list of files + selecting a file in the list of files and then clicking on OK + entering the file name in the File Name text box and clicking on OK Note: In this dialog box, the default directory is the one specified first with the `import_path' configuration variable. 3.2.1. Error checking As the file is being opened, HoTMetaL checks for fatal SGML errors. Fatal errors include start-tags without matching end-tags, invalid element names, and many other SGML errors. In such cases, HoTMetaL displays a message describing the problem. It then gives you the following choices: 1. Import Through Filter, which allows you to run the file through a filter that may correct the errors. If you choose this option you will get a dialog box in which to give the name of an output file. Enter the output filename (including drive and directory) in the Output File text box, or click on the Choose File... button to get a file selection dialog box with which to choose a file. HoTMetaL will then invoke the filter: when the filter has finished, HoTMetaL attempts to open the output file. 2. Open the file as a text file so that you can correct the errors manually. When you've done this, you can run the Interpret Document command, which performs the equivalent of Open... on the text document. 3. Cancel the operation and correct the error(s) through other means. If no errors are found, the file is formatted, and checked once more for errors as if the Turn Rules Checking On command in the Special menu had been selected for the new file. At this stage, non-fatal errors may be detected. Examples of these are incorrectly placed elements, and text at a point where no text is permitted. Errors of this kind do not prevent the file from being opened. Finally the file is validated: this stage of error checking ensures that the HTML markup is correct and complete. The following example illustrates the difference between rules checking and validation: if you open a file that has an HTML element that does not contain a HEAD element, rules checking will not complain, because you have not yet violated the rules file. Validation, however, will alert you to the fact that the required HEAD element is missing. Note: There will sometimes be a document type declaration (DOCTYPE) at the top of an HTML file, specifying which DTD to use. This declaration is ignored with files being opened with HoTMetaL, because all HTML files use the HTML DTD. 3.3. Open Template... This command allows you to work with templates, which are pre-defined structures for documents. Templates are used as forms or document outlines that you can enter text into without having to insert any of the markup yourself. 3.3.1. Opening a template To open a template, click on the Open Template... command. This brings up a file selection dialog box labeled Open Template. If you have a templates directory (see below) the dialog box will display the files from that directory Each file corresponds to a template: to open a template, just open it from this dialog box as you would any other file. The document name in the title bar will be the same as the template name, but with a number added to the first part of the filename: for example, the first time you open a template called fax.htm, the new document will be called fax1.htm, the second time the document will be calledfax2.htm, and so forth. When the template file is opened you can enter text or elements into it, and later save the file. When you save the file, you will have use the Save As... command and choose a new file name--the name in the title bar is not automatically adopted. If you save this file in the templatesdirectory make sure you do not overwrite the original template file by mistake. 3.3.2. Creating your own templates A number of templates are shipped with HoTMetaL, but it is expected that you will normally be working with templates that were created at your own site. 3.3.2.1. Templates directory In order for you to work with templates successfully, a directory must be designated as the templates directory. This is a central location containing all of your template files, and it is the directory whose files are displayed when the Open Templates... dialog box comes up. By default, this is the directory called tmplts in the directory where HoTMetaL is installed. If you want to use another directory for this purpose, you will have to name that directory using the templates_path configuration variable. For example: templates_path=c:\susan\tmplts If the default templates directory does not exist (perhaps someone has removed it), and no alternativedirectory is specified with the templates_path variable, the current directory will be used as the templatesdirectory. 3.3.2.2. Creating templates To create a template file with HoTMetaL, you should do the following: * Create a document as you normally would. * Invoke the Save As... command in the File menu. * Choose a directory and filename. You can save the file directly in the templates directory or move it there later. * Click on the Save As button. 3.3.2.3. Installing a template When the template file has been created, it should be saved in the templatesdirectory (or you can save it elsewhere and move it later) so that it will be easily accessible from the Open Template dialog box. 3.4. Save This command saves the current file (that is, the file that is opened in the active document window) to the disk. HoTMetaL saves the document in the file name shown in the title bar at the top of the window. 3.4.1. Save options There are several save options that you may set if you need to do so. All of these options are set using configuration variables: + You may choose to save a document type declaration (DOCTYPE), at the top of the file. The default may be set by setting the export_doc_type_dec configuration variable to YES or NO: export_doc_type_dec=YES + You may choose to save an SGML declaration at the top of the file. The default may be set by setting the export_sgml_dec configuration variable to YES or NO. Note: Normally you should use this feature only if your file will be used by some other SGML system. Some browsers may not be able to read an SGML declaration, or may display (unwanted) information from the declaration on the screen. + If your file contains special characters (those outside the ASCII range 0-127), you may choose to have these converted to SGML character references when the file is saved. This situation arises only if your file was edited with another editor. Special characters that are entered in the document when it is being edited with HoTMetaL will be converted immediately to character entity icons. Character references are represented in a HoTMetaL document as a small, rectangular icon, similar to a character entity icon, labelled `#nnn', where the n's are numbers. For example: #200. Browsers should display a character reference as the character itself. The default setting for this option (YES or NO) may be set with the export_convert_special_chars configuration variable. + You can choose the character(s) that HoTMetaL uses to mark the end of a line in the saved file. You may choose one of the values MAC, UNIX, and MSDOS, which will cause the end-of-line character to be carriage return, line feed, or carriage return and line feed, respectively The default end-of-line marker can be set with the export_eol configuration variable. If you don't provide a value for this variable, the default will be MSDOS. + For elements that are formatted in fill mode (see the documentation on the Characters... menu item) you can set the length of lines in the saved file by telling HoTMetaL to insert end-of-line characters after a specified number of characters. This option can be turned on or off by default by setting the export_add_line_breaks configuration variable to YES or NO.The number of characters in a line can be set with the export_max_line_len configuration variable, e.g., export_max_line_len=75 HoTMetaL will not cause a line break in the saved file to occur between an element and adjoining text. If you have rules checking turned on, the file will be validated, and you will be warned if there are errors and asked if you still want to save. If you do, the file will be invalid and HoTMetaL may have trouble opening it in the future. 3.5. Save As... This command lets you choose a new name for the current document. When you save a file with this command, HoTMetaL creates a new file whose content is the same as the current file, and closes the current file, leaving the new file open. The document that was closed will look the same as it did the last time it was saved: any changes that were made since the last save will be saved in the newly created file. HoTMetaL gives you the file selection dialog box with which to specify the name of the new file. You should follow the same instructions for selecting a file or directory as were described in the section on the Open... command. Note: In this dialog box, the default directory is the one specified first by the `export_path' configuration variable. The save options that were specified for Save will also apply to the Save As... command. Save As... will validate the file if rules checking is turned on, just as Save does. 3.6. Close File This command closes the current file. If the file has had changes made to it since it was last saved, you will be prompted to save the changes before closing it. 3.7. Preview When you invoke this command it will launch a browser to display the file. If the file hasn't been saved since changes were last made to it, HoTMetaL will prompt you to save the file. You then have the choice of saving the file or proceeding with the previewing operation without saving (in which case the document is saved to a temporary file automatically). The command line for the browser that is launched by this command is specified using the html_browser configuration variable. The default value for this variable (and therefore the default browser) isc:\mosaic\mosaic.exe. Invoking this command does the same as if you had saved the file with HoTMetaL, launched the browser independently of HoTMetaL, and then opened the file with the browser. 3.8. Publish... This command is a form of "find and replace" for URLs. Before a completed HTML document is moved to a WWW server, all URLs should refer to documents that are available on some WWW server. (While the document is being created, they may refer to documents on your local system.) The Publish... command gives you the opportunity to edit all the URLs, modifying them if necessary. For example, when you are creating a document the URLs may consist of local filenames such as: file:///c|/rodney/orwell/homage.htm When the document is placed on your server, you must substitute URLs that refer to documents that are available on your server or some other server. For example: http://www.sq.com/orwell/homage.htm When you invoke Publish... you will get a dialog box containing two text boxes. The first box (labeled Change URLs From) contains a part of the URL that you want to change; the second box (labeled To) contains the string that you want to change it to. The default values in these two boxes are specified by two configuration variables: publish_change_from specifies the part of the URL that should be changed; publish_change_to specifies the new value for this part of the URL. If there were a large number of URLs for which you needed to change a local directory such as file:///c|/rodney to a directory on the server, such as http://www.sq.com, you could set your configuration variables as follows: publish_change_from=file:///c|/rodney publish_change_to=http://www.sq.com This would cause the Change URLs From text box to contain "file:///c|/rodney" and the To text box to contain "http://www.sq.com". 3.8.1. Finding and Replacing URLs When you click on the Find Next button, HoTMetaL finds the next element that has an attribute representing a URL (often the HREF attribute of the element A and the SRC attribute of the element IMG). The search starts at the insertion point (or selection). When an element with a URL is found, the insertion point is placed inside that element, and the document scrolls to its location. If the URL contains the text in the Change URLs From box, clicking on the Replace button will change it to the text in the To box. Clicking on the Replace All button will make this change for all URLs in the document that contain the Change URLs From text. This also causes the dialog box to be dismissed. You can edit the Change URLs From and To text if you want to perform substitutions other than the default one. The searching performed by this command does not wrap around from the bottom to the top of the file. 3.9. Exit Quits HoTMetaL. If an open file has been changed since the last time it was saved, you will be prompted to save the file before exiting. 4. The Edit menu The Edit menu contains commands to cut, copy, and paste a selection, undo your last action, perform find and replace operations, and do spell checking. 4.1. Undo Allows the effect of the last operation to be undone. Most commands can be undone. There are, however, some HoTMetaL actions that cannot be undone: + any command from the File menu, except Publish + scrolling and windowing commands + text selection + Undo itself (it can be undone with Redo) + Show Structure View, Show Link and Context View + Any actions performed prior to the last time the document was saved cannot be undone. If you imagine a sequence of undo-able commands as a list, successive Undo commands will proceed through the list, starting at the most recent. Therefore, if you execute two Undo commands in a row you will undo the most recent action, and then undo the second most recent action. Note that since Undo is not itself an undo-able command, one Undo cannot undo another. This function is reserved for Redo, which is the inverse of Undo. (See the section on Redo.) If you undo a Copy or Cut command, the previous contents of the clipboard will be restored. 4.1.1. Undo limit The number of previous commands that can be undone is not limitless but rather is controlled by an undo limit. Once this limit is reached, each successive command will cause the oldest undoable command to be committed, that is, it will no longer be possible to undo that command. For example, if the undo limit is set to 1 and you Cut a selection and then Paste what you just cut, you will be able to undo the paste but not the cut. If the undo limit were 2 or greater, both the cut and paste could be undone. The default value for the undo limit is 10, but this can be changed by setting the undo_limit configuration variable, e.g.: undo_limit=20 4.2. Redo This command allows the most recent undone command to be redone. Redo operates in a way similar to Undo: a sequence of Redo commands re-does the most recent redo-able commands (i.e., commands that have been undone) in reverse order. Redo and Undo are inverses of each other: the net effect of an Undo and its corresponding Redo is to cause no change to the document. If an undoable action is performed after a series of one or more Undo commands then the Undo commands will no longer be redo-able. To illustrate how Redo works, suppose you Cut a selection in a document, and then Paste that selection somewhere else. If you perform two Undo commands, first the Paste and then the Cut will be undone. If you then execute a Redo, the Cut will be redone. A second Redo will then redo the Paste. 4.3. Cut Removes the current selection from the document and places it in the clipboard. Any previous contents of the clipboard will be erased. The selection can then be pasted. This command is used when you want to remove a section of text that will probably be pasted in elsewhere, in the same or another document. 4.4. Copy Copies the contents of the current selection into the clipboard and erases any previous contents. The document is left unchanged. This command is used when you want to duplicate a portion of the document without erasing it. The copied selection can be inserted elsewhere using the Paste command. 4.5. Paste Transfers the contents of the clipboard to the document. If the document contains an insertion point, the clipboard is pasted at that point; if it contains a selection, then the contents of the clipboard overwrite the selection. The clipboard can contain markup. If the paste would result in an incorrectly marked-up document, you may be prompted to either cancel the paste operation or continue with rules checking turned off. Some paste operations cannot be performed even with rules checking turned off. 4.6. Find and Replace... Allows text, elements, and patterns to be found and replaced. You are presented with a dialog box that allows you to enter various values and parameters. 4.6.1. Specifying the search and replace strings The Find text box allows you to specify a search string of text characters, elements, character entities, or patterns. If the document contains a selection when you invoke Find and Replace... the selected text will automatically become the search string. If the selected text is longer than 255 characters, it will be truncated. If the selection contains a markup icon (an element or character entity) it will be truncated at the last character before the icon. A selection that starts with a markup icon will become a null search string, and therefore an existing selection cannot be used to cause an element to be the search string. The Replace text box allows you to specify a replace string consisting of text characters, patterns, an element, or a character entity, with which you want to replace the search string. The Find In text box allows you to restrict your search to a particular element. The Find, Replace, and Find In strings are described in more detail below. 4.6.2. Command buttons There are five buttons (including Cancel) along the bottom of the Find & Replace dialog box, which allow you to carry out several search and replace operations. 4.6.2.1. Find Find causes HoTMetaL to search through the document for the search string according to the various search parameters chosen. If you click on Find and the search is successful, HoTMetaL selects the text, character entity, or element that was found and scrolls to the selection. If the search fails, HoTMetaL will beep. Also, a Not found message will be displayed at the bottom of the Find & Replace dialog box. Text searches will not match if parts of the search string are found within different elements. If you are searching for `Fred and Barney', but the word `and' is in a separate element (emphasized, for example), the search string will not be matched. 4.6.2.2. Replace Replace replaces the current selection in the document with the replace string. This command is enabled only when part of the document is selected. 4.6.2.3. Replace then Find Replace then Find replaces the current selection in the document with the replace string, and then resumes the search procedure. This command will be enabled only when part of the document is selected. You would use this option if you wanted to manually examine each occurrence of the search string before doing a replacement: if you decide to perform the replacement, click on Replace then Find again; otherwise, click on Find to go to the next occurrence of the search string. 4.6.2.4. Replace All Replace All replaces all occurrences of the search string with the replace string. This command automates the whole find and replace process, not giving you the opportunity to choose individual cases. It is possible that some of the occurrences of the search string that are found cannot be replaced, because this would cause an incorrectly marked-up document. If so, these occurrences are skipped over. After the operation has been completed, a message will be displayed in the Find & Replace dialog box showing how many occurrences of the search string were found, and how many were replaced. The insertion point will now be at the end of the last replacement. Invoking the Undo command after Replace All will cause all of the replacements that were actually made to be undone. 4.6.3. Specifying search patterns When the Find Patterns option is on (see below), the characters you type in the Find textbox are interpreted as patterns by HoTMetaL: that is, the search string can contain certain special search characters that allow the search string to match a class of strings, or markup constructs. If your search string does not contain any special search characters, HoTMetaL will search for exactly the text you have typed. On the other hand, if the search string does contain special search characters, it defines a pattern of characters to be matched. For example, the search character `.' (period) is used in the pattern m...y to match a sequence of five characters beginning with `m' and ending with `y', e.g., the words `money', `marry', `murky', etc. A complete description of search characters and expressions appears below. The following characters are special search characters in a search pattern: \ . * ? + ^ $ ] In addition, the characters `&' and `<' are special when one or the other appears as the first character of the pattern. If you want to search for any of these as ordinary characters when Find Patterns is turned on, it must be preceded by a backslash. For example, \. is used to match a period. Search patterns are sequences of ordinary characters and special characters, combined according to certain rules. The following list summarizes how these search characters are interpreted, and how search patterns are formed. + An ordinary character represents itself. + A string beginning with a `<', immediately followed by an element name (and possibly attributes and content, as discussed below), is used to match an element. + A period or dot, `.', represents a single, arbitrary character (including a blank). So fo.d would match `food', `ford', `fond', `fold', etc. Similarly, s.o. matches `stop', `shot', `snow', etc. + A single character, or a string enclosed in parentheses, followed by an asterisk, `*', matches zero or more occurrences of that character or string. For example, l*ama would match `ama', `lama', `llama', `lllama', etc. b(an)*a would match `ba', `bana', `banana', and so on. It is possible to combine the `*' with `.' to match arbitrary strings of characters. So s.*ch matches `search', `such', `stretch', `stopwatch', as well as `sch' and `skip lunch'. This search pattern represents strings that start with `s' followed by zero or more occurrences of an arbitrary single character (it doesn't have to be the same character over and over) followed by the characters `ch'. Since the period can match a blank space, this pattern can match a multi-word string. + A single character, or a string enclosed in parentheses, followed by a question mark, `?', matches zero or one occurrences of that character or string. For example, to search for instances of both `color' and `colour', you would use: colou?r + A single character, or a string enclosed in parentheses, followed by a plus sign, `+', matches one or more occurrences of that character or string. For example, the following expression matches `ben', `been', `beeen', and so forth, but not `bn'. be+n + Search patterns may be enclosed within parentheses for grouping. + Search patterns separated by a vertical bar, `|', match any string that matches either of the patterns. For example, if you wanted to search for either `love' or `money', you would use the expression: love|money In a more complex example, you could combine two search patterns given above: s.*ch|fo.d + A caret, `^', at the very beginning of a search pattern means that text will match the pattern only if it immediately follows markup (a start- or end-tag, or a character entity). Such text must not be separated from the markup by white space. Anywhere else, the caret is not treated as a special search character (except in sub-strings, see below). For example, if you wanted to search for the word `Note' immediately following markup, you could use: ^Note + A dollar sign, `$', at the very end of a search pattern means that text will match the pattern only if it is immediately followed by markup. Such text must not be separated from the markup by white space. Anywhere else, the dollar sign is not treated as a special search character. For example, if you wanted to search for the word `sub' immediately preceding markup, you could use: sub$ + A pair of square brackets, `[' and `]', around any string of characters defines a sub-string that matches any one of the characters between the brackets. For example, an[dy] matches `and' and `any'. By contrast, a string of characters preceded by a caret, `^', within brackets, matches any character not in the string. For example, th[^ei][a-z]* matches any word that begins with `th', which is not followed by an `e' or `i'. It would match `that' and `thought' but not `therefore' or `this'. + A sub-string, within square brackets, of the form [char1-char2] matches any character in the range of ASCII characters beginning at char1 and ending at char2. For example, the sub-string [e-p] matches any lowercase letter between `e' and `p', inclusive. The substring [A-Za-z] matches any upper- or lower-case letter. Note that if searching is not in case-sensitive mode (see below), no distinction between lower case and upper case letters is made in character ranges. In this case, for example, the character range [a-z] would match any upper- or lower-case letter. + An expression of the form [^char1-char2] matches any character not in the range of ASCII characters beginning at char1 and ending at char2. + A range can occur inside a sub-string. For example, the pattern: [ac-fh] matches any of `a', `c' through `f', and `h'. + If you wish to use any of the characters `^', `]', or `-' as a literal character within a sub-string rather than as a special search character, there are certain rules you must follow. + The `^' character is special only if it occurs as the first character in a sub-string. Otherwise, it's treated as a literal character. E.g., [joy^] will match any of the characters `j', `o', `y', and `^'. + The character `-' is a special search character if it occurs between other characters in the sub-string. If it occurs at the beginning or end of the sub-string, it is a literal character. For example, the sub-string [a-] will match `a' or `-'. + The character ']' terminates a sub-string unless it occurs as the first character. For example, []ab] will match `a' or `b' or `]'. But [ab]] matches `a' or `b' followed by `]'. None of the otherwise special search characters, including `\' and `[' has special meaning within a sub-string. + If you surround a sub-expression in the search string by parentheses, `(' and `)', you can refer in the replace string to whatever this sub-expression matches. In general, an expression in the replace string of the form `\n', where n is a number from 1 to 9, means "replace this expression with whatever the nth expression in brackets in the search string has matched". For example, if the search string is (.*)read and the replace string is \1ox then if the search string matches `bread', the found text will be replaced by `box'. This is because the sub-expression `(.*)' matched the letter `b'; the expression `\1' in the replace string means "replace this expression with whatever is matched by the first expression in parentheses in the search string". Therefore `b' is substituted for `\1' and the replace string becomes `box'. Here is a more complicated example: suppose the search string is (v.*e) (v.*a) and the replace string is \2 \1 Now the search string may match the words `vice versa'. The first sub-expression, `(v.*e)', matches `vice' and the second sub-expression, `(v.*a)', matches `versa'. In the replace string, HoTMetaL replaces `\2' by what the second sub-expression in the search string matched, and replaces `\1' by what the first sub-expression matched. Therefore the replace string becomes `versa vice'. The net effect of the operation is to replace an occurrence of `vice versa' with `versa vice'. It is possible to nest sub-expressions. In this situation, the sub-expressions are numbered according to the order of occurrence of their left parentheses. For example, if the search string were (a(bc)d) and the replace string \2 \1 the effect would be to find `abcd' and replace it by `bc abcd'. The expression `\0' in a replace string refers to the entire string that was matched by the search string. E.g., if the search string were fish and the replace string were gone \0ing then an occurrence of `fish' would be replaced by `gone fishing'. 4.6.4. Elements and character entities as search patterns A search string that begins with an open angle bracket, `<', followed by a valid element name matches an element of that name. If the search succeeds, the insertion point is positioned to the left of the start tag. It does not matter here or in other search options whether tags are visible or not (see Show/Hide Tags in the View menu). The name in the search string can optionally be followed by a closing angle bracket (>). For example, The would match the word `The' anywhere within the element P. This is similar to the kind of restrictive searching that can be done using the Find In string but it can be used in conjunction with that feature to further restrict the search. In the last example, if the Find In string is set to: